Add exact writer epoch opens - #9
Merged
Merged
Conversation
Member
Author
|
Validation update:
|
xav-db
force-pushed
the
codex/exact-writer-epoch
branch
from
August 31, 2026 10:31
c64286e to
7e23044
Compare
xav-db
marked this pull request as ready for review
August 31, 2026 11:35
xav-db
added a commit
to HelixDB/helix-db
that referenced
this pull request
Aug 31, 2026
## Summary - open every managed writer with the caller supplied nonzero authority epoch - rely on native SlateDB epoch fencing for lower-term, equal-term, concurrent, and delayed stale opens - add a request-local commit gate for bounded drain classification without durable receipts or replay - expose terminal retry classification across the Rust, TypeScript, Python, and Go SDKs ## Stack - SlateDB exact-epoch dependency: HelixDB/slatedb#9 - pinned SlateDB commit: c64286ec8e5aaa724f12a8c54b58fe73efcff534 - consumed by Hyperscale: HelixDB/helix-hyperscale#260 ## Safety - only a verified pre-execution rejection can return request ownership - commit-start and drain-abort claims are mutually exclusive - unknown write outcomes are terminal and never automatically retried - authority exhaustion at u64::MAX remains intentionally unsupported ## Validation Locked all-target/all-feature workspace compile passes on SlateDB 0.15. Managed-writer lower/equal, concurrent, delayed stale, and in-flight fencing tests pass. The locked migration parity dev suite passes end-to-end. Fresh CI is rerunning after the final Python contract formatting fix; full tests, Clippy, docs, SDK, and linked nine-node validation remain in progress. <!-- greptile_comment --> <h3>Greptile Summary</h3> The PR introduces exact-epoch managed-writer fencing, typed reader-retirement cancellation, and terminal classification for unknown commit outcomes. It also aligns the transport and SDK error contracts and expands fencing, lifecycle, migration, and scale coverage. - Managed writer opens pass a nonzero caller-supplied authority epoch to SlateDB while embedded writer behavior remains separate. - Reader retirement cooperatively cancels admitted reads with a dedicated stable error code. - HTTP reports unknown commit outcomes as unavailable with an explicit non-retryable marker; gRPC reports them as unavailable with stable metadata. - Rust, TypeScript, Python, and Go SDKs expose explicit retry classification without inferring retryability from status alone. - CI and production contract coverage gain dedicated vector-migration scale and writer-fencing checks. <details><summary><h3>Important Files Changed</h3></summary> | Filename | Overview | |----------|----------| | crates/db/src/lib.rs | Adds the managed-writer open mode, propagates exact authority epochs to SlateDB, and exercises stale, equal, concurrent, and in-flight fencing behavior. | | crates/db/src/execution_control.rs | Adds monotonic reader-retirement cancellation and integrates it with deadline-aware cooperative execution. | | crates/db/src/error.rs | Introduces typed retirement cancellation and classifies fenced commit outcomes as terminal rather than transaction conflicts. | | crates/db/src/query_service.rs | Exposes predicates that let transports distinguish reader retirement, deadlines, conflicts, and unknown commit outcomes. | | crates/server/src/http.rs | Maps unknown commit outcomes to HTTP 503 and emits an explicit `retryable: false` field. | | crates/server/src/grpc.rs | Maps unknown commit outcomes to gRPC Unavailable while retaining the stable error code in metadata. | | sdks/rust/src/lib.rs | Preserves explicit retry metadata on remote errors and retries only when the server supplies Boolean true. | | sdks/typescript/src/index.ts | Adds optional retry metadata and fail-closed retry classification to the TypeScript error contract. | | sdks/python/src/helixdb/_client_common.py | Parses explicit retry metadata in both current and legacy envelopes and exposes fail-closed retry classification. | | sdks/go/client.go | Adds optional retry metadata to remote errors and requires explicit true for retryable classification. | </details> <details><summary><h3>Sequence Diagram</h3></summary> ```mermaid sequenceDiagram participant C as Managed caller participant H as HelixDB participant S as SlateDB participant T as Transport participant SDK as Client SDK C->>H: Open writer with nonzero authority epoch H->>S: Open using exact writer epoch S-->>H: Writer opened or fenced C->>H: Execute write H->>S: Commit transaction alt commit succeeds S-->>H: Committed H-->>T: Success else fencing makes outcome unknown S-->>H: Fenced commit result H-->>T: Unknown outcome T-->>SDK: "503 / unavailable, retryable=false" SDK-->>C: Terminal error end ``` </details> <sub>Reviews (1): Last reviewed commit: ["Accept disjoint membership storage in re..."](85e6a97) | [Re-trigger Greptile](https://app.greptile.com/api/retrigger?id=58590933)</sub> <details><summary><h4>Context used (4)</h4></summary> - Knowledge Base — [Database engine](https://app.greptile.com/helixdb/-/custom-context/knowledge-base/helixdb/helix-db/-/docs/database-engine.md) - Knowledge Base — [Interpreter execution](https://app.greptile.com/helixdb/-/custom-context/knowledge-base/helixdb/helix-db/-/docs/interpreter-execution.md) - Knowledge Base — [Client SDKs and bindings](https://app.greptile.com/helixdb/-/custom-context/knowledge-base/helixdb/helix-db/-/docs/client-sdks-and-bindings.md) - Knowledge Base — [Server and transports](https://app.greptile.com/helixdb/-/custom-context/knowledge-base/helixdb/helix-db/-/docs/server-and-transports.md) </details> <!-- /greptile_comment -->
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Stack
Required by HelixDB slatedb#1018 and Hyperscale slatedb#260.
The dependency revision is c64286e.